prod deploy 4.2.1 - #263

Release PR review (develop → master, 4.2.0 → 4.2.1).

Gitflow / version: correct. Base is master, head is develop, and the version bump (pyproject.toml ×2 + src/polyswarm/__init__.py) is exactly the release step AGENTS.md prescribes — all three sites are in sync at 4.2.1.

1. .gitlab-ci.yml — include: project: '$CI_TEMPLATE' (correctness, blocking-ish)

$CI_TEMPLATE is defined nowhere in this repo (only reference is the include itself), so it has to come from a group/project CI/CD variable. Two things to confirm before merging, because this is the pipeline that runs release-pypi on master:

• If the variable is unset for this project, include resolves to an empty project path and the entire pipeline fails to load — no tests, no publish.
• If it's defined as a protected variable, it's only exposed on protected branches. master would work; every unprotected feature/* pipeline would break at config-load time. Feature branches are where CI is supposed to gate merges into develop.

Also worth noting this is an unrelated infra change riding a release PR — it's on develop so it's in scope by construction, but it wasn't soaked by anything (the templating change only takes effect once pipelines run under the new include).

2. stage-blue / stage-eu-blue baked into API_URI_SHORTCUTS (correctness)

src/polyswarm/client/polyswarm.py:50,53 now ship blue/green slot hostnames in a PyPI artifact:

'stage':    'https://api.stage-blue.polyswarm.network/v3',
'stage_eu': 'https://api.stage-eu-blue.polyswarm.network/v3',

A slot name is by definition not stable — after a cutover to green, --stage / --stage-eu in released 4.2.1 point at the wrong (or decommissioned) environment, and there's no fix short of another release. stage-v3 / stage-eu-v3 read like the stable CNAMEs this shortcut wants. If *-blue really is the permanent ingress and the -v3 names are gone, fine — but please say so in the PR body, because tests/api_uri_test.py:48 documents its intent as "guard against the constant drifting from the verified ingress hosts" and that guard was updated to match the code, which makes it a tautology unless a human verified the hosts.

Note this is a user-visible change to a documented flag surface (help text on --stage / --stage-eu) shipping under a patch bump. Defensible if it's a fix, but it deserves a line in the release notes rather than being silent.

3. winget → commercial (fine)

Cassette tests/vcr/test_kgb_create_get_json.vcr looks like a genuine re-record, not a hand-edit — instance/record ids, timestamps, SDK user-agent and both Content-Lengths all moved coherently (115→119 = +4 for the longer source, 236→241 = +5). That's the workflow specs/04-testing.md:40 asks for. No stray winget left in the tree; the other two KGB cassettes use nsrl and are untouched, correctly. known_good_field_test.py sort assertion still holds (commercial < nsrl).

One thing the diff doesn't answer: was winget removed server-side as a valid source, or just renamed? kgb.py:19 takes click.STRING with no validation, so the CLI doesn't care either way — but if the set of valid sources is now a fixed vocabulary, specs/02-commands.md:21 is the place to record it, since nothing in the repo documents what a valid source is.

4. SDK pin (minor)

The re-recorded cassette was captured against polyswarm_api/4.1.0 while pyproject.toml still floors at >=4.0.0,<5.0.0. Nothing in this diff needs 4.1.0, so the floor is probably still honest — just flagging that the only environment these cassettes have actually been exercised against is 4.1.0, per the "floor it at the lowest version exposing everything the CLI uses" rule in specs/05-sdk-contract.md:69.

5. PR body

"is this a prod deploy" isn't a release description. This is the PR that publishes to PyPI the moment it lands on master — the body should enumerate what's shipping (notably the --stage host change, which consumers will notice).

Nothing here blocks on spec drift: specs/01-architecture.md:21 describes API_URI_SHORTCUTS behaviourally and doesn't enumerate hostnames, so it stays accurate.